Please test your applications on this version, and report all bugs using the
bug reporter on Apple Developer Connection:
http://developer.apple.com/bugreporter/index.html
Release Components
NetSprocket Release Notes - this file
NetSprocket.h - the header file to compile with
NetSprocketStubLib - the stub lib for your development environment
NetSprocketLib - release version of the library
NetSprocketDebugLib - debugging version of the library
WARNING: don't place both the debugging and non-debugging versions of the
library in the search path or you will not be sure which version you will be
using.
CRITICAL NOTE:
a rather severe error has been found in the documentation for NetSprocket. The original "Apple Game Sprockets Guide 1.0" documentation said that you should call NSpReleaseAddressReference() to free the memory used by address references. You must make sure that you only use this on address references that were allocated by NetSprocket (such as NSpDoModalJoinDialog(). This is especially critical when using address references generated by the NSpConvertOTAddrToAddressReference() function. If you allocate your own OTAddress structions and then convert them to NSpAddressReferences you should not use NSpReleaseAddressReference() to free this memory. Release your OTAddress allocations as you normally would.
A note on game names
When you are hosting a game with NetSprocket you provide a name for the game in the host dialog. When playing over AppleTalk this name is used with NBP (Name Binding Protocol) to advertise your game on the LAN. There are a few special characters that should not be used in game names because they have special meaning in AppleTalk. These characters are:
* - asterisk
≈ - option x
/ - forward slash
@ - at sign
: - colon
Dependencies
NetSprocket requires Mac OS 8.1 or later.
NetSprocket requires the latest Universal Headers -- version 3.2 or later.
The latest version of the Universal Headers can be found on the Mac OS SDK
CD-ROMs or on Apple Developer Connection. <http://developer.apple.com/sdk/>
Changes from 1.1.1 to 1.7
Changes:
- NetSprocket 1.7 no longer supports 68K. It is PowerPC-only.
- Added NSpSetConnectTimeout(UInt32 inSeconds). This will set the timeout for
new NetSprocket connections. For example, if you set this value to 5 then after
five seconds NetSprocket will stop trying to create a connection. If you set the
value to zero then it returns to the TCP default of 4 minutes.
- If you have installed an asynchronous message handler for your NetSprocket game
then you will now receive several new messages related to player and group managemnt.
When a group is created you'll receive an NSpCreateGroupMessage.
When a group is deleted you'll receive an NSPDeleteGroupMessage.
You'll receive similar messages when players are added/removed from groups. See the
1.7 version of NetSprocket.h for the new message.what constants and message structures.
- Added a new call for servers: NSpPlayer_GetAddress. You give it a player ID and a
it will fill in an OTAddress structure for you with the received address for that
player. This is useful if the player is behind a gateway that is performing Network
Address Translation. By using this new call the server can find out the translated
address of the player.
- Added NSpPlayer_ChangeType so that the server can dynamically change the player type
during a network session.
- Added NSpPlayer_Remove so that the server can forcibly removed players from a game.
- There was a bug in all previous versions of NetSprocket that caused groups to be created
twice on the machine which requested the group. This has been fixed.
Changes from 1.1 to 1.1.1
Changes:
- NetSprocket 1.1.1 is one library rather than being separate binaries for
CFM68K and PowerPC.
- If you specify a NULL string for the "type" parameter to NSpDoModalJoinDialog,
NetSprocket will use the game ID (passed to NSpInitialize) to search for games
on the AppleTalk network. This matches the behavior for NSpGame_Host. You may
also pass in a zero length pascal string for the same behavior. The pascal
string method also worked on version 1.1.
Bug Fixes:
- NetSprocket now includes the resources ('dlgx', 400) and ('dlgx', 403)
so that it won't interfere with application dialogs.
- Through the power of C++ all previous NetSprocket builds subversively
had many debug asserts in them. This has been corrected. This should
fix a number of problems.
- NetSprocket's dialogs would occasionally truncate one or more of the
text fields. This has been corrected.
- All callback functions were receiving invalid game references. Also, the
callback function would be called inside of NSpGame_Host before the game
reference was filled in. Both problems are fixed.
- A couple of rare instances where NetSprocket could leak memory were corrected.
Known Issues:
- Host renegotiation does not work.
- NetSprocket 1.0 does not implement Round-Trip-Time or throughput functions.
You can implement your own RTT and thruput functions on top of the
NetSprocket API yourself, though.
- If you attempt to connect to an invalid OTAddress, NetSprocket will block inside
OpenTransport until the connection times out (~2 minutes).
Changes from 1.0 to 1.1
Changes:
- This version now supports CFM68K as well.
- The NSpPlayerLeftMessage now includes a field for the name of the player who
left the game. Previously, you only got the playerID, but since the player
was done there was no way to perform a GetInfo to get their name.
CAVEAT I: Be advised that this is a new feature to NetSprocket 1.1 and is
NOT backwards compatible with pre-1.1 builds. If you use this field you must
make sure that your are using NetSprocket 1.1 or newer. You can get the version
number with the NSpGetVersion() call.
In short, make sure that everyone in the game is using 1.1 or newer if you
plan to use this field of the structure.
Bug fixes:
- Bugs that disallowed the creation of more than one game object at a time
have been fixed. You are now only limited by other system resources,
such as memory or networking ports. Keep in mind if you try to host
multiple games that you will get an error back if you try to host multiple
games with the same game name (for AppleTalk) or with the same port (for IP).
- A significant problem was found under heavy flow (traffic) conditions
that could cause data to be delivered out of order. This has been fixed.
Getting the Most Out of NetSprocket
There is a new version of NetSprocketTest that should provide a better example
of how to effectively use NetSprocket. The most important thing to note is how
NetSprocket messages are handled both synchronously and asynchronously. This
method prevents problems where user actions, such as a mouse-down, could
prevent the main event loop from calling NSpMessage_Get, and thereby cause
a buffer overflow problem.
The number one problem we've seen with people using NetSprocket is apps running
out of memory. The reason this happens is that NetSprocket presents a
message API to the application. If you have, say, a 50K message, NetSprocket
doesn't hand that message to the client application until all 50K are received.
This model makes NetSprocket much more susceptible to low memory problems than
other, data-oriented, networking APIs. There are three things you can
do to minimize this kind of problem.
1. Use small messages ( < 1K) as often as is practical
2. Give NetSprocket as much memory as you can spare
3. Use the async message hander
NetSprocket will still function if you don't do these things, but end user
conditions will be much more likely to cause your app problems.
You should always check return values from NetSprocket functions. Failure to
do so is reckless, and will only cause you and your customers headaches.
If the user unchecks the "play on this machine" button, the hosting machine
must not send any messages to other players. The host machine only acts to
route messages between the various players -- while it can act on messages
that are copied to it, it cannot directly message other players. If the host
needs to send messages to other players, the host should be implemented as a
special kind of player. If you need to disable the "play on this machine"
button, create a custom host dialog box that does not provide that option.
When connecting to a game for the first time, a client application is not
permitted to send messages to other players until it receives the join
approved message. The application should spin waiting for a join approved,
join denied, or game terminated message. If you do receive a join denied or
game terminated message, you are not permitted to send messages to any other
players in the game. In actuality, the connection to the host has already
been terminated. Future versions of NetSprocket may return control to the
client app before the connection is completely established, so assuming you
can send messages immediately after the NSpGame_Join call has returned is an
error.
To get the optimal performance out of NetSprocket, design your game to send
"Normal" messages that contain less than 550 bytes of data. This allows
NetSprocket to use datagram-level delivery for both TCP/IP and AppleTalk.
Using "Registered" messages can cause a 2-50% network performance degradation,
depending on a number of factors, including network bandwidth, utilization,
message size, and send frequency.
All messages, except ones sent from a player to himself, are sent through the
host. Therefore, the host is one "hop" from any other player, and two non-host
players are always two "hops" apart.
Sending a message to a group is not as efficient as sending to everyone in the
game, or to a single player. It is usually more efficient than sending to each
individual in the group separately.
You CAN NOT send messages at VBL (or any other interrupt) time with NetSprocket
1.0. You should schedule a deferred system task, or just wait until system
task time before sending. You CAN however, call NSpMessage_Get at interrupt
time. We generally recommend against all interrupt-time calls to the Game
Sprockets.
The number of players in a NetSprocket game is limited only by memory (and
networking resources, such as available ports). If you expect to handle lots
of players (14+), you need to make sure you give NetSprocket sufficient memory
and queue elements when you initialize it. If you get send failed or memory
error message from NetSprocket, try giving it more memory.
If you have a situation where your game has players whose network throughput is
greatly disparate, you need to make sure you don't choke the slow person. For
example, if you have 4 players on AppleTalk over Ethernet, and you have a fifth
player join the game over a 28.8k PPP connection, and your fast machines are
sending messages 30 times a second each, you're going to quickly gag the
newcomer with too much data, and the host will simply not be able to deliver
messages as quickly as you generate them. The newcomer will be disconnected
after approximately 20 messages have been queued up, waiting for flow control
to lift before delivering them. You can avoid this type of problem by
throttling down your game's send rate to allow the newcomer to participate.
You can also avoid it by sending "Junk" messages instead of Normal.
